feat: add two-phase extension upgrade with spec.schemaVersion#328
Draft
WentingWu666666 wants to merge 13 commits intodocumentdb:mainfrom
Draft
feat: add two-phase extension upgrade with spec.schemaVersion#328WentingWu666666 wants to merge 13 commits intodocumentdb:mainfrom
WentingWu666666 wants to merge 13 commits intodocumentdb:mainfrom
Conversation
WentingWu666666
force-pushed
the
developer/two-phase-extension-upgrade
branch
3 times, most recently
from
a3bdb5c to
c0d35b1
Compare
Add spec.schemaVersion field to DocumentDBSpec to decouple binary (image) upgrades from schema (ALTER EXTENSION) upgrades. This provides a rollback-safe window between deploying a new binary and committing the schema change. Three modes: - Empty (default): Two-phase mode. Schema stays at current version until user explicitly sets schemaVersion. Safe by default for production. - "auto": Auto-finalize. Schema updates to match binary version automatically. Simple mode for development and testing. - Explicit version: Schema updates to exactly that version. Must be <= binary. Changes: - api/preview/documentdb_types.go: Add SchemaVersion to DocumentDBSpec - internal/controller/documentdb_controller.go: Add determineSchemaTarget() function, modify upgradeDocumentDBIfNeeded() to gate ALTER EXTENSION on spec.schemaVersion value - internal/utils/util.go: Add SemverToExtensionVersion() inverse conversion - Regenerated CRDs (config/crd + helm chart) - Added unit tests for all three modes and edge cases - Created public upgrade documentation (docs/operator-public-documentation/) - Added Upgrading DocumentDB page to mkdocs.yml navigation Closes documentdb#271 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Wenting Wu <wentingwu@microsoft.com>
WentingWu666666
force-pushed
the
developer/two-phase-extension-upgrade
branch
from
c0d35b1 to
525700b
Compare
Add a ValidatingWebhookConfiguration that enforces: - schemaVersion must be <= binary version (on create and update) - Image rollback below installed schema version is blocked (on update) Components added: - internal/webhook/documentdb_webhook.go: ValidateCreate/ValidateUpdate handlers - internal/webhook/documentdb_webhook_test.go: 18 unit tests - Helm template 10_documentdb_webhook.yaml: Issuer, Certificate, Service, ValidatingWebhookConfiguration with cert-manager CA injection - Updated 09_documentdb_operator.yaml: webhook port, cert volume mount, args - Updated cmd/main.go: webhook registration The webhook runs inside the existing operator process on port 9443 using cert-manager for TLS (same pattern as the sidecar injector). failurePolicy is set to Fail for database safety. The controller retains defense-in-depth checks as a secondary safety net. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Wenting Wu <wentingwu@microsoft.com>
Restructure webhook to use two validation function slices following the
CNPG ClusterCustomValidator pattern:
- validate(db) spec-level rules run on both create and update
Contains: validateSchemaVersionNotExceedsBinary
- validateChanges(new, old) update-only rules comparing old vs new
Contains: validateImageRollback
This makes it easy to add new validation rules just append a function
to the appropriate slice. Each validator has a consistent signature
returning field.ErrorList, and errors from all validators are aggregated.
Also adds var _ webhook.CustomValidator = &DocumentDBValidator{} compile
check and uses apierrors.NewInvalid for proper Kubernetes error format.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Wenting Wu <wentingwu@microsoft.com>
- Remove Step 1b (image rollback blocking) from controller webhook handles it - Simplify determineSchemaTarget: keep lightweight defense-in-depth guard - Rename Pg-suffixed variables to full names (schemaExtensionVersion, etc.) - Refactor webhook tests to Ginkgo/Gomega (matching CNPG and controller patterns) - Add suite_test.go for webhook package Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Wenting Wu <wentingwu@microsoft.com>
- Reframe upgrade types as Operator (control plane) vs DocumentDB (data plane) - Explain documentDBVersion vs schemaVersion relationship clearly - Reorganize data plane upgrade as step-by-step walkthrough with production/dev tabs - Add Multi-Region Upgrades section with coordination guidance - Move Advanced Image Overrides to its own section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
CNPG default is in-place restart. Switchover promotes a replica first, then restarts the old primary as replica, minimizing write downtime. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add
spec.schemaVersionfield to DocumentDBSpec to decouple binary (image) upgrades from schema (ALTER EXTENSION) upgrades. This provides a rollback-safe window between deploying a new binary and committing the schema change.Closes #271
Three Modes
User Flow (Two-Phase)
Changes
Backward Compatibility
Breaking change: Default behavior changes from auto-update to two-phase. Existing users upgrading to this operator version will need to set schemaVersion: "auto" to restore previous behavior, or adopt two-phase upgrades. This is intentional -- safe by default for a database operator.